﻿//-----------------------------------------------------------------------------------------
// <copyright file="Camera.cs" company="Jakub Florczyk (www.jakubflorczyk.pl)">
//      Copyright © 2009 Jakub Florczyk (www.jakubflorczyk.pl)
//      http://samsungmobilesdknet.codeplex.com
// </copyright>
//-----------------------------------------------------------------------------------------

namespace SamsungMobileSDKNET
{
    using System;
    using System.Runtime.InteropServices;
    using DirectShow;

    /// <summary>
    /// Specifies error codes specific to the Advanced Camera API.
    /// </summary>
    public enum CameraError
    {
        /// <summary>
        /// Auto focus failed.
        /// </summary>
        AutoFocusFailed = ResultCode.CameraResultBase,

        /// <summary>
        /// Value not supported.
        /// </summary>
        ValueNotSupported = ResultCode.CameraResultBase + 1
    }

    /// <summary>
    /// Specifies ISO values.
    /// </summary>
    public enum CameraISO
    {
        /// <summary>
        /// Auto ISO mode.
        /// </summary>
        Auto,

        /// <summary>
        /// ISO 50 mode.
        /// </summary>
        I50,

        /// <summary>
        /// ISO 100 mode.
        /// </summary>
        I100,

        /// <summary>
        /// ISO 200 mode.
        /// </summary>
        I200,

        /// <summary>
        /// ISO 400 mode.
        /// </summary>
        I400,

        /// <summary>
        /// ISO 800 mode.
        /// </summary>
        I800
    }

    /// <summary>
    /// Specifies metering values.
    /// </summary>
    public enum CameraMetering
    {
        /// <summary>
        /// Center metering.
        /// </summary>
        Center,

        /// <summary>
        /// Matrix metering.
        /// </summary>
        Matrix,

        /// <summary>
        /// Spot metering.
        /// </summary>
        Spot
    }

    /// <summary>
    /// Specifies autofocus values.
    /// </summary>
    public enum CameraAutoFocusMode
    {
        /// <summary>
        /// Autofocus is off.
        /// </summary>
        Off,

        /// <summary>
        /// Normal mode.
        /// </summary>
        Normal,

        /// <summary>
        /// Macro mode.
        /// </summary>
        Macro,

        /// <summary>
        /// Face mode.
        /// </summary>
        Face
    }

    /// <summary>
    /// Specifies Camera Source values.
    /// </summary>
    public enum CameraID
    {
        /// <summary>
        /// Higher-end camera typically on the back of the phone.
        /// </summary>
        Primary,

        /// <summary>
        /// Lower-end camera typically on the front of the phone, used for example for video conferencing.
        /// </summary>
        Secondary
    }

    /// <summary>
    /// Specifies capabilities supported by the Advanced Camera API.
    /// </summary>
    [StructLayout(LayoutKind.Sequential)]
    public struct CameraCapabilities
    {
        /// <summary>
        /// Camera ISO setting support. TRUE if setting is supported, otherwise is FALSE.
        /// </summary>
        public bool IsoIsSupported;

        /// <summary>
        /// Camera light metering support. TRUE if setting is supported, otherwise is FALSE.
        /// </summary>
        public bool MeteringIsSupported;

        /// <summary>
        /// Camera autofocus support. TRUE if setting is supported, otherwise is FALSE.
        /// </summary>
        public bool AutoFocusIsSupported;

        /// <summary>
        /// Camera Wide Dynamic Range (WDR) support. TRUE if setting is supported, otherwise is FALSE.
        /// </summary>
        public bool WdrIsSupported;

        /// <summary>
        /// Image stabilization support. TRUE if setting is supported, otherwise is FALSE.
        /// </summary>
        public bool ImageStabilizationIsSupported;
    }

    /// <summary>
    /// Samsung Advanced Camera API.
    /// </summary>
    /// <remarks>
    /// Samsung's Advanced Camera API extends Microsoft's DirectShow API so that camera applications can take advantage of advanced digital camera features.
    /// <br/><br/>
    /// The Advanced Camera API also enables you to switch between the primary rear-facing camera and the secondary front-facing camera on supported phones with dual cameras.
    /// <br/><br/>
    /// Note: the features supported by the Advanced Camera API are generally only present on phones with high-end cameras, such as the Samsung Omnia.  Not all functionality is supported on all phones.
    /// </remarks>
    public class Camera
    {
        /// <summary>
        /// Gets the phone's camera capabilities.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <param name="capabilities">A pointer to the capabilities of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if no camera is present on the phone 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if capabilities is NULL or camHandle is NULL or invalid 
        /// </returns>
        [Obsolete("Deprecated in SDK 1.2.0 - use GetCapabilitiesEx instead.")]
        [DllImport(Common.DllName, EntryPoint = "SmiCameraGetCapabilities")]
        public static extern ResultCode GetCapabilities(
            [In] IBaseFilter camHandle,
            [Out] out CameraCapabilities capabilities);

        /// <summary>
        /// Gets the phone's camera capabilities.
        /// </summary>
        /// <param name="camId">Camera ID.</param>
        /// <param name="capabilities">A pointer to the capabilities of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if no camera is present on the phone 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if capabilities is NULL or camHandle is NULL or invalid 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraGetCapabilitiesEx")]
        public static extern ResultCode GetCapabilitiesEx(
            [In] CameraID camId,
            [Out] out CameraCapabilities capabilities);

        /// <summary>
        /// Sets the ISO setting of camera.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <param name="iso">ISO value of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorFeatureNotSupported"/> if ISO setting is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camhandle is NULL or invalid or iso is invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.CameraError.ValueNotSupported"/> if ISO value is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraSetISO")]
        public static extern ResultCode SetISO(
            [In] IBaseFilter camHandle,
            [In] CameraISO iso);

        /// <summary>
        /// Sets the metering setting of camera.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <param name="meter">Metering value of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorFeatureNotSupported"/> if metering setting is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camera handle is NULL or invalid or meter value is invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.CameraError.ValueNotSupported"/> if meter value is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraSetMetering")]
        public static extern ResultCode SetMetering(
            [In] IBaseFilter camHandle,
            [In] CameraMetering meter);

        /// <summary>
        /// Sets the autofocus setting of camera.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <param name="focus">Focus value of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorFeatureNotSupported"/> if autofocus setting is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if video capture filter instance is NULL or invalid or focus value is invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.CameraError.ValueNotSupported"/> if focus value is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraSetAutoFocusMode")]
        public static extern ResultCode SetAutoFocusMode(
            [In] IBaseFilter camHandle,
            [In] CameraAutoFocusMode focus);

        /// <summary>
        /// Performs autofocus action on the camera. Autofocus will be performed based on the mode set previously through the <see cref="M:SamsungMobileSDKNET.Camera.SetAutoFocusMode"/> API.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> if autofocus succeeds 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.CameraError.AutoFocusFailed"/> if autofocus fails 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorFeatureNotSupported"/> if autofocus setting is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camera handle is NULL or invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        /// <remarks>
        /// This method can take several seconds to complete, depending on light conditions and subject movement.
        /// </remarks>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraPerformAutoFocus")]
        public static extern ResultCode PerformAutoFocus(
            [In] IBaseFilter camHandle);

        /// <summary>
        /// Resets autofocus on the camera.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorFeatureNotSupported"/> if autofocus setting is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camera handle is NULL or invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraResetAutoFocus")]
        public static extern ResultCode ResetAutoFocus(
            [In] IBaseFilter camHandle);

        /// <summary>
        /// Turns on WDR setting on the camera.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorFeatureNotSupported"/> if wdr setting is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camera handle is NULL or invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraTurnOnWDR")]
        public static extern ResultCode TurnOnWDR(
            [In] IBaseFilter camHandle);

        /// <summary>
        /// Turns off WDR setting on the camera.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorFeatureNotSupported"/> if wdr setting is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camera handle is NULL or invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraTurnOffWDR")]
        public static extern ResultCode TurnOffWDR(
            [In] IBaseFilter camHandle);

        /// <summary>
        /// Turns on Image Stabilization setting on the camera.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorFeatureNotSupported"/> if image stabilization setting is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camera handle is NULL or invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraTurnOnImageStabilization")]
        public static extern ResultCode TurnOnImageStabilization(
            [In] IBaseFilter camHandle);

        /// <summary>
        /// Turns off Image Stabilization setting on the camera.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorFeatureNotSupported"/> if image stabilization setting is not supported 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camera handle is NULL or invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraTurnOffImageStabilization")]
        public static extern ResultCode TurnOffImageStabilization(
            [In] IBaseFilter camHandle);

        /// <summary>
        /// Creates the video capture filter instance for the given camera ID and loads the instance.
        /// </summary>
        /// <param name="camId">The camera ID.</param>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if primary/secondary camera is not present 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camera ID or camHandle is invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        /// <remarks>
        /// For more description, please refer programming guide.
        /// </remarks>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraOpen")]
        public static extern ResultCode Open(
            [In] CameraID camId,
            [In] IBaseFilter camHandle);

        /// <summary>
        /// Releases the video capture filter instance and returns the system to the default state that was present before calling the <see cref="M:SamsungMobileSDKNET.Camera.Open"/> API.
        /// </summary>
        /// <param name="camHandle">Video capture filter instance of the camera.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if camHandle is invalid 
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiCameraClose")]
        public static extern ResultCode Close(
            [In] IBaseFilter camHandle);        
    }
}
